              <div align="right">
${TARGET="offline"}                <a href="${LDAP_SDK_HOME_URL}" style="font-size: 85%">LDAP SDK Home Page</a>
${TARGET="offline"}                <br>
                <a href="${BASE}index.${EXTENSION}" style="font-size: 85%">Product Information</a>
              </div>

              <h2><a href="index.${EXTENSION}">LDAPv3 Wire Protocol Reference</a></h2>
              <h3>The LDAP Extended Operation</h3>

              <p>One of the biggest improvements that LDAPv3 offers over LDAPv2 is its extensibility, particularly in the form of controls (which can be used to provide additional information alongside requests and responses), SASL mechanisms (which can be used to provide support for a variety of authentication types), and extended operations (which can be used to perform all kinds of processing not covered by the core LDAPv3 operation types.</p>

              <p>Some standard extended operation types are:</p>

              <ul>
                <li>StartTLS — Adds TLS encryption to a connection that was established without communication security. Defined in <a href="../specs/rfc4511.txt" target="_blank">RFC 4511</a> section 4.14.</li>
                <li>Password Modify — Changes a user’s password. Defined in <a href="../specs/rfc3062.txt" target="_blank">RFC 3062</a>.</li>
                <li>Who Am I? — Retrieves the current authorization identity for the client connection. Defined in <a href="../specs/rfc4532.txt" target="_blank">RFC 4532</a>.</li>
                <li>Cancel — Cancels a request already in progress on the connection. Defined in <a href="../specs/rfc3909.txt" target="_blank">RFC 3909</a>.</li>
                <li>Start Transaction — Begins an LDAP transaction. Defined in <a href="../specs/rfc5805.txt" target="_blank">RFC 5805</a> section 2.1.</li>
                <li>End Transaction — Commits or aborts an LDAP transaction. Defined in <a href="../specs/rfc5805.txt" target="_blank">RFC 5805</a> section 2.3.</li>
              </ul>

              <p>Directory server vendors may also define their own extended operation types for various purposes. For example, some of the other extended operation types offered by the Ping Identity Directory Server (formerly UnboundID Directory Server) include:</p>

              <ul>
                <li>Password Policy State — Retrieves or updates a variety of password policy state information for a user.</li>
                <li>Get Password Quality Requirements — Retrieves information about the requirements that a password must meet for the server to accept it.</li>
                <li>Multi-Update — Allows sending multiple types of updates (add, delete, modify, and modify DN operations) in a single request to be processed in an atomic or non-atomic fashion.</li>
                <li>Deliver One-Time Password — Causes the server to send a one-time password to a specified user through some out-of-band mechanism (e.g., SMS, email message, voice call, etc.) for use in conjunction with the UNBOUNDID-DELIVERED-OTP SASL mechanism.</li>
                <li>Deliver Password Reset Token — Causes the server to send a token through some out-of-band mechanism that will allow a user to reset a forgotten password, expired password, or locked account.</li>
                <li>Generate TOTP Shared Secret — Updates a user entry to support authentication with time-based one-time passwords via the <tt>UNBOUNDID-TOTP</tt> SASL mechanism.</li>
                <li>Register YubiKey OTP Device — Registers a YubiKey OTP device for a user, which will allow that user to authenticate with the <tt>UNBOUNDID-YUBIKEY-OTP</tt> SASL mechanism.</li>
                <li>Get Changelog Batch — Retrieves information about changes processed within the server that match a given set of criteria.</li>
              </ul>

              <p>A detailed explanation of all of these extended operation types is outside the scope of this document. But we will use the StartTLS and password modify extended operations in the course of illustrating the encoding of extended requests and responses.</p>

              <a name="extended-request"></a>
              <h3>The Extended Request</h3>

              <p>The extended request protocol operation is defined in <a href="../specs/rfc4511.txt" target="_blank">RFC 4511</a> section 4.12:</p>

              <pre>ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
     requestName      [0] LDAPOID,
     requestValue     [1] OCTET STRING OPTIONAL }</pre>

              <p>And <tt>LDAPOID</tt> is defined earlier in <a href="../specs/rfc4511.txt" target="_blank">RFC 4511</a> as an octet string with values constrained to be valid object identifiers (OIDs). The BER type for an extended request protocol operation is <tt>0x77</tt> (application class, constructed, tag number twenty-three).</p>

              <p>Every extended request must have an OID, which identifies the type of request, and it may optionally include a value that provides additional information for use in processing that request. If there is a value, its encoding will vary based on the type of operation.</p>

              <a name="extended-response"></a>
              <h3>The Extended Response</h3>

              <p>The extended response protocol op is also defined in <a href="../specs/rfc4511.txt" target="_blank">RFC 4511</a> section 4.12:</p>

              <pre>ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
     COMPONENTS OF LDAPResult,
     responseName     [10] LDAPOID OPTIONAL,
     responseValue    [11] OCTET STRING OPTIONAL }</pre>

              <p>This means that it’s got all the components of the <tt>LDAPResult</tt> sequence (which we’ve already covered in a <a href="ldap-result.${EXTENSION}">previous section</a>), plus an optional OID to identify the type of response, and an optional value to include additional information. The BER Type for the extended response is <tt>0x78</tt> (application class, constructed, tag number twenty-four).</p>

              <p>An OID is really only necessary if a single request can yield multiple types of responses, but some types of extended responses always include an OID even if they’re the only kind of response for the associated request. In cases where the response has an OID, that OID may be the same as or different from the request OID.</p>

              <a name="unsolicited-notifications"></a>
              <h3>Unsolicited Notifications</h3>

              <p>The vast majority of the time, LDAP is a request-response protocol. The client sends a request, and the server sends back one or more responses. But sometimes, the server might need to send a message to the client without there having been a corresponding request. For example, if the server is shutting down, it would be nice to tell any connected clients about it before disconnecting them. This can be accomplished with unsolicited notifications.</p>

              <p>An unsolicited notification is simply an extended response that the server sends to the client without a corresponding extended request. Unsolicited notifications always use a message ID of zero, and they always have a <tt>responseName</tt> element (an OID) to indicate what kind of notification it is. They may or may not have a <tt>responseValue</tt>, and they may use other LDAPResult fields to provide additional information to the client.</p>

              <p><a href="../specs/rfc4511.txt" target="_blank">RFC 4511</a> defines one type of unsolicited notification: the notice of disconnection notification (in section 4.4.1). It is used to indicate that the server is about to close the connection to the client for some reason (e.g., because the server is shutting down, because the connection has been idle for too long, because the client did something the server didn’t like, etc.). The notice of disconnection unsolicited notification has an OID of <tt>1.3.6.1.4.1.1466.20036</tt> and no value. The result code may provide a general indication of the disconnect reason, and there may be a diagnostic message with additional details.</p>

              <p>For example, let’s say that the server wants to send a notice of disconnection to the client with a result code of <tt>unavailable</tt> (52) and a diagnostic message of “<tt>The Directory Server is shutting down</tt>”. That unsolicited notification would be encoded as follows:</p>

              <pre>30 49 -- Begin the LDAPMessage sequence
   02 01 00 -- The message ID (integer value 0)
   78 44 -- Begin the extended response protocol op
      0a 01 34 -- unavailable result code (enumerated value 52)
      04 00 -- No matched DN (0-byte octet string)
      04 25 54 68 65 20 44 69 72 65 -- The diagnostic message (octet string
            63 74 6f 72 79 20 53 65 -- "The Directory Server is shutting down")
            72 76 65 72 20 69 73 20
            73 68 75 74 74 69 6e 67
            20 64 6f 77 6e
      8a 16 31 2e 33 2e 36 2e 31 2e -- The extended response OID (octet string
            34 2e 31 2e 31 34 36 36 -- "1.3.6.1.4.1.1466.20036")
            2e 32 30 30 33 36</pre>

              <a name="extended-operation-example-starttls"></a>
              <h3>Example: The StartTLS Extended Operation</h3>

              <p>As a first example, let’s look at a StartTLS extended request, which is defined in <a href="../specs/rfc4511.txt" target="_blank">RFC 4511</a> section 4.14. This request has an OID of <tt>1.3.6.1.4.1.1466.20037</tt> and no value. A StartTLS request with message ID one is encoded as follows:</p>

              <pre>30 1d -- Begin the LDAPMessage sequence
   02 01 01 -- The message ID (integer value 1)
   77 18 -- Begin the extended request protocol op
      80 16 31 2e 33 2e 36 2e 31 2e -- The extended request OID
            34 2e 31 2e 31 34 36 36 -- (octet string "1.3.6.1.4.1.1466.20037"
            2e 32 30 30 33 37       -- with type context-specific primitive zero)</pre>

              <p>The StartTLS response doesn’t have a value, but it may optionally contain an OID. If it doesn’t have an OID, then the StartTLS extended response is just a simple <tt>LDAPResult</tt>. But if it does have an OID, then that OID must be the same as the request OID (<tt>1.3.6.1.4.1.1466.20037</tt>). The following example demonstrates the appropriate encoding for a successful StartTLS response that does include the OID:</p>

              <pre>30 24 -- Begin the LDAPMessage sequence
   02 01 01 -- The message ID (integer value 1)
   78 1f -- Begin the extended response protocol op
      0a 01 00 -- success result code (enumerated value 0)
      04 00 -- No matched DN (0-byte octet string)
      04 00 -- No diagnostic message (0-byte octet string)
      8a 16 31 2e 33 2e 36 2e 31 2e -- The extended response OID
            34 2e 31 2e 31 34 36 36 -- (octet string "1.3.6.1.4.1.1466.20037"
            2e 32 30 30 33 37       -- with type context-specific primitive zero)</pre>

              <p>Note that the StartTLS response is always sent in the clear; the TLS negotiation doesn’t happen until after the StartTLS response is sent, and then everything after that point will be encrypted.</p>

              <a name="extended-operation-example-password-modify"></a>
              <h3>Example: The Password Modify Extended Operation</h3>

              <p>The password modify extended operation, defined in <a href="../specs/rfc3062.txt" target="_blank">RFC 3062</a>, is a little more complicated than the StartTLS operation, since the request always includes a value, and the response may optionally include a value.</p>

              <p>The password modify extended request has an OID of <tt>1.3.6.1.4.1.4203.1.11.1</tt>. The value is BER-encoded and uses the following encoding:</p>

              <pre>PasswdModifyRequestValue ::= SEQUENCE {
  userIdentity    [0]  OCTET STRING OPTIONAL
  oldPasswd       [1]  OCTET STRING OPTIONAL
  newPasswd       [2]  OCTET STRING OPTIONAL }</pre>

              <p>The elements of this request value are:</p>

              <ul>
                <li><tt>userIdentity</tt> — This identifies the user for whom to change the password. According to <a href="../specs/rfc3062.txt" target="_blank">RFC 3062</a> section 2.1, it “may or may not be a DN”, which allows for some leeway in its interpretation. If the value isn’t a DN, then some servers may expect it to use the authorization identity format described in <a href="../specs/rfc4513.txt" target="_blank">RFC 4513</a> section 5.2.1.8 (which is either “dn:” followed by the DN of the target user, or “u:” followed by the username). If no <tt>userIdentity</tt> value is included in the request, then the server should assume that the currently-authenticated user wants to change their own password.</li>
                <li><tt>oldPasswd</tt> — This specifies the current password for the user. It may be absent if an administrator is changing the password for another user, and some servers may allow it to be absent even when a user is changing their own password. But if it is present, then it must match the user’s current password or the server will reject the request.</li>
                <li><tt>newPasswd</tt> — This specifies the new password for the user. It may be absent to indicate that the server should generate the new password.</li>
              </ul>

              <p>For example, let’s consider a password modify request with message ID 1, a <tt>userIdentity</tt> of <tt>uid=jdoe,ou=People,dc=example,dc=com</tt>, an <tt>oldPasswd</tt> of <tt>secret123</tt>, and no <tt>newPasswd</tt> value. That request would be encoded as follows:</p>

              <pre>30 53 -- Begin the LDAPMessage sequence
   02 01 01 -- The message ID (integer value 1)
   77 4e -- Begin the extended request protocol op
   80 17 31 2e 33 2e 36 2e 31 2e -- The extended request OID
         34 2e 31 2e 34 32 30 33 -- (octet string "1.3.6.1.4.1.4203.1.11.1"
         2e 31 2e 31 31 2e 31    -- with type context-specific primitive zero)
   81 33 -- Begin the extended request value
      30 31 -- Begin the value sequence
         80 24 75 69 64 3d 6a 64 6f 65 -- The userIdentity (octet string
               2c 6f 75 3d 50 65 6f 70 -- "uid=jdoe,ou=People,dc=example,dc=com"
               6c 65 2c 64 63 3d 65 78 -- with type context-specific primitive zero)
               61 6d 70 6c 65 2c 64 63
               3d 63 6f 6d
         81 09 73 65 63 72 65 74 31 32 -- The oldPasswd (octet string "secret123"
               33                      -- with type context-specific primitive one)</pre>

              <p>The password modify extended response doesn’t include a response OID. It may optionally include a response value, but that will only be if the request didn’t specify a <tt>newPasswd</tt> value and the server generated a new password for the target user. In that case, the response value will have the following encoding:</p>

              <pre>PasswdModifyResponseValue ::= SEQUENCE {
  genPasswd       [0]     OCTET STRING OPTIONAL }</pre>

              <p>If we assume that the server successfully processed the above request and generated a password of <tt>AdapterSystemGrainPlaymate</tt>, then the extended response would have the following encoding:</p>

              <pre>30 2f -- Begin the LDAPMessage sequence
   02 01 01 -- The LDAP message ID (integer value 1)
   78 2a -- Begin the extended response protocol op
      0a 01 00 -- success result code (enumerated value 0)
      04 00 -- No matched DN (0-byte octet string)
      04 00 -- No diagnostic message (0-byte octet string)
      8b 21 -- Begin the extended response value
         30 1f -- Begin the value sequence
            80 1d 41 64 61 70 74 65 72 53 -- The genPasswd (octet string
                  74 65 76 65 6e 73 6f 6e -- "AdapterSystemGrainPlaymate" with
                  47 72 61 69 6e 50 6c 61 -- type context-specific primitive zero)
                  79 6d 61 74 65</pre>

              <p></p>

              <table border="0" width="100%">
                <tr>
                  <td align="left">Previous: <a href="delete.${EXTENSION}">The LDAP Delete Operation</a></td>
                  <td align="right">Next: <a href="modify.${EXTENSION}">The LDAP Modify Operation</a></td>
                </tr>
              </table>
